Personalize API

A unique key specific to each API implementation. It identifies the specific application or client for reporting, permissions, and merchandising. This is provided by Algonomy.

Example: apiClientKey=b0126f995ac848159d

A unique key that identifies the site. Each Algonomy client has a unique API key to separate data and traffic from other clients. This is provided by Algonomy.

Example: apiKey=4faeaf752ee40a0f

Add to Cart ID. This can be a single product ID or a list of product IDs. If more than one product is added to the cart, separate the product IDs by using the pipe "|" character.

Example: atcid=uv2345|xt1234

Block content item(s). This can be a single content ID or a list of content IDs. If more than one content ID is specified, separate the content IDs by using the pipe "|" character.

Example: bi=content__1|content__2

Name of the JavaScript function that JSON data will be passed to. It must be specified for JSONP. The value of this parameter is used as the name of the js function in the response.

Example: callback=products_returned

Omits category data (categoryIds and categories) when set to false. The default is true.

Example: categoryData=false

The category ID of the category the merchant wants to investigate. The value must match the external ID provided by the merchant to Algonomy for the category.

Example: categoryId=902312

List of content IDs. The content returned is the intersection between the list of content ids passed in the API call and the content from the selected Campaign. Mulptiple content IDs are separated by the pipe "|" character.

Example: content_ids=content__13055|13056

Note: The provided contentId's should be external Ids.

Cart value. Used for targeted campaigns involving cart value. It's expressed in cents; for example, $10 is represented as 1000.

Example: cv=9550 (this would equal $95.50)

True/false. If true, it omits the HTML returned in the Algonomy server response. If false, the response includes the HTML for the placement which is set in the layout of the html field. The default is false. 

Example: excludeHtml=true

The brand featured on the page. Used to set the seed for brand-seeded strategies, such as Brand Top Sellers.

Example: fpb=Microsoft

Shopper IP address. Only use if the API request is not coming from the shopper’s device (for example, server-side integration).

Example: ipor=255.255.255.255

True/false. The default is false. If true, it includes rcs string.

Example: includeRcs=true

True/false. The default is false. If true, the response will include the score of the selected content for each placement.

Example: includeScore=true

True/false. The default is false. If true,the response will include a list of tags for the selected content.

Example: includeTags=true

List of placement identifiers. Each identifier consists of a page type and a placement name. The identifiers are separated by the pipe "|" character.

You'll receive one piece of content per placement. All placements in a call must be for the same page type.

Example: placements=item_page.horizontal|item_page.vertical

Shopper’s referrer prior to viewing the page. Used for reporting and merchandising. This is highly recommended.

Example: pref=http://www.google.com

A single product ID, or a list of product IDs. Part of an order definition on the purchase complete page. Use the pipe "|" character to separate the product IDs.

Example: productId=uv2345|xt1234

Algonomy Cookie String. This is the encrypted Algonomy cookie for the user associated with the API request. It should be passed exactly as it was received in a prior API response.

Clients should ensure to preserve the 'rcs' value just as it was served. The 'rcs' parameter is always alphanumeric and case-sensitive, with the token value including a mix of uppercase letters, lowercase letters, and numbers.

Note: The 'rcs' parameter allows merchants to effectively provide the Algonomy platform access to a user's Algonomy browser cookie by acting as a cookie proxy (or cookie pass-through). This process involves the merchant reading and writing a user's Algonomy browser cookie and passing it to and from Algonomy via the server-side API.

Products the shopper has purchased in the current session. This can be a single product ID or list of product IDs. Products listed here will be considered along with historical data from the Algonomy system. Use the pipe "|" character to separate the product IDs.

Example: recentlyPurchased=uv2345|xt1234

Region ID. Must be consistent with the ID used in the Engage Content Feed.

Example: rid=Switzerland-France

Identifies a single visit by a shopper.  Sessions are used by behavioral models (to scope user behavior in a shopping session) and reporting metrics.

Example: sessionId=93484

Supply user segments. Used for segment-targeted campaigns. List each segment using the format segment_number:segment_name, and then use the pipe "|" character to separate segments. You must pass both the segment ID and a segment name for each segment.

Example: sgs=101:NewUser|202:Male

When set to true, returns http/https depending on how the variable is named in the layout.

ssl=true

Filter contents that match a list of tags using advanced logic such as AND (&&), OR (||), and NOT (!) operators.

Note: You need to URL encode the '&&' operator. To encode a URL with the ampersand character, use %26.

Multiple tags can be passed using the pipe "|" as a separator. When multiple tags are passed, the returned content should have all tags.

Example: tagFilter=(shoes||women)&&Nike

Filter of (shoes OR women) AND Nike

Note: You can also group together the logical expressions to combine multiple expressions.

Refine contents based on a list of tags. The tags in this list will be applied as a filter if there are matching contents available. But if there are no matching contents, then these tags will not be applied as filters. Multiple tags can be passed using the pipe "|" as a separator.

Example: tagFilter=shoes||women&tagRefinement=Nike

This would attempt to return contents with either 'shoes' AND 'Nike' OR 'women' AND 'Nike'. If no contents have the Nike tag, then it will still return contents with either 'shoes' OR 'women'.

Note: tagRefinement will only be applied if tagFilter is being used.

Custom keys and values that describe the current shopper. Separate information using a semicolon and the pipe "|" character.

Example: userAttribute=eye_color:blue;green|hair_color:brown

Usage is same as userAttribute, except that the attributes sent along with userAttributeReplace will replace all previously sent values for that attribute.

Example: userAttributeReplace=eye_color:black

In the above example all previous values of eye_color will be removed and replaced with black.

If the same attribute is sent along in a single request in userAttribute as well as userAttributeReplace, then the value sent in userAttributeReplace will take precedence.

This attribute also supports Delete update against attribute values. Example: userAttribute=eye_color:|hair_color:

List of placements with promotions based on the request. This is an array of JSON objects, each describing a single placement..

A list of the creatives to be displayed. In most cases, this will only be one.

Destination URL will be converted for clickTracking purposes and will redirect to the original click through URL

Fully formed HTML for the placement based on the layout and selected campaign. It is included in the response by default. Turn off by using the excludeHtml request parameter.

A list of the creatives to be displayed. In most cases, this will only be one.

Either ‘ok’ or ‘error’.